Get (Apache Ant API)

org.apache.tools.ant.taskdefs

## Class Get

- java.lang.Object
- - org.apache.tools.ant.ProjectComponent
  - - org.apache.tools.ant.Task
    - - org.apache.tools.ant.taskdefs.Get

- All Implemented Interfaces:
    java.lang.Cloneable

      public class Get
      extends Task

  Gets a particular file from a URL source. Options include verbose reporting, timestamp based fetches and controlling actions on failures. NB: access through a firewall only works if the whole Java runtime is correctly configured.
  Since:
    Ant 1.1

- - ### Nested Class Summary

    Nested Classes
    Modifier and Type | Class and Description
    --- | ---
    `protected static class` | `Get.Base64Converter` Provide this for Backward Compatibility.
    `static interface` | `Get.DownloadProgress` Interface implemented for reporting progress of downloading.
    `static class` | `Get.NullProgress` do nothing with progress info
    `static class` | `Get.VerboseProgress` verbose progress system prints to some output stream

  - ### Field Summary

    - ### Fields inherited from class org.apache.tools.ant.Task

      `target, taskName, taskType, wrapper`

    - ### Fields inherited from class org.apache.tools.ant.ProjectComponent

      `description, location, project`

  - ### Constructor Summary

    Constructors
    Constructor and Description
    `Get()`

  - ### Method Summary

    Methods
    Modifier and Type | Method and Description
    --- | ---
    `void` | `add(FileNameMapper fileNameMapper)` Add a nested filenamemapper.
    `void` | `add(ResourceCollection rc)` Adds URLs to get.
    `Mapper` | `createMapper()` Define the mapper to map source to destination files.
    `boolean` | `doGet(int logLevel, Get.DownloadProgress progress)` Deprecated. only gets the first configured resource
    `boolean` | `doGet(java.net.URL source, java.io.File dest, int logLevel, Get.DownloadProgress progress)` make a get request, with the supplied progress and logging info.
    `void` | `execute()` Does the work.
    `void` | `log(java.lang.String msg, int msgLevel)` Logs a message with the given priority.
    `void` | `setDest(java.io.File dest)` Where to copy the source file.
    `void` | `setHttpUseCaches(boolean httpUseCache)` HTTP connections only - control caching on the HttpUrlConnection: httpConnection.setUseCaches(); if false, do not allow caching on the HttpUrlConnection.
    `void` | `setIgnoreErrors(boolean v)` If true, log errors but do not treat as fatal.
    `void` | `setMaxTime(long maxTime)` The time in seconds the download is allowed to take before being terminated.
    `void` | `setPassword(java.lang.String p)` password for the basic authentication.
    `void` | `setQuiet(boolean v)` If true, set default log level to Project.MSG_ERR.
    `void` | `setRetries(int r)` The number of retries to attempt upon error, defaults to 3.
    `void` | `setSkipExisting(boolean s)` Skip files that already exist locally.
    `void` | `setSrc(java.net.URL u)` Set an URL to get.
    `void` | `setTryGzipEncoding(boolean b)` Whether to transparently try to reduce bandwidth by telling the server ant would support gzip encoding.
    `void` | `setUserAgent(java.lang.String userAgent)` HTTP connections only - set the user-agent to be used when communicating with remote server.
    `void` | `setUsername(java.lang.String u)` Username for basic auth.
    `void` | `setUseTimestamp(boolean v)` If true, conditionally download a file based on the timestamp of the local copy.
    `void` | `setVerbose(boolean v)` If true, show verbose progress information.

    - ### Methods inherited from class org.apache.tools.ant.Task

      `bindToOwner, getOwningTarget, getRuntimeConfigurableWrapper, getTaskName, getTaskType, getWrapper, handleErrorFlush, handleErrorOutput, handleFlush, handleInput, handleOutput, init, isInvalid, log, log, log, maybeConfigure, perform, reconfigure, setOwningTarget, setRuntimeConfigurableWrapper, setTaskName, setTaskType`

    - ### Methods inherited from class org.apache.tools.ant.ProjectComponent

      `clone, getDescription, getLocation, getProject, setDescription, setLocation, setProject`

    - ### Methods inherited from class java.lang.Object

      `equals, finalize, getClass, hashCode, notify, notifyAll, toString, wait, wait, wait`

- - ### Constructor Detail

    - #### Get

          public Get()

  - ### Method Detail

    - #### execute

          public void execute()
                       throws BuildException

      Does the work.
      Overrides:
        `execute` in class `Task`
      Throws:
        `BuildException` - Thrown in unrecoverable error.

    - #### doGet

          @Deprecated
          public boolean doGet(int logLevel,
                                 Get.DownloadProgress progress)
                        throws java.io.IOException

      Deprecated. only gets the first configured resource
      make a get request, with the supplied progress and logging info. All the other config parameters are set at the task level, source, dest, ignoreErrors, etc.
      Parameters:
        `logLevel` - level to log at, see `Project.log(String, int)`
        `progress` - progress callback; null for no-callbacks
      Returns:
        true for a successful download, false otherwise. The return value is only relevant when `ignoreErrors` is true, as when false all failures raise BuildExceptions.
      Throws:
        `java.io.IOException` - for network trouble
        `BuildException` - for argument errors, or other trouble when ignoreErrors is false.

    - #### doGet

          public boolean doGet(java.net.URL source,
                      java.io.File dest,
                      int logLevel,
                      Get.DownloadProgress progress)
                        throws java.io.IOException

      make a get request, with the supplied progress and logging info. All the other config parameters like ignoreErrors are set at the task level.
      Parameters:
        `source` - the URL to get
        `dest` - the target file
        `logLevel` - level to log at, see `Project.log(String, int)`
        `progress` - progress callback; null for no-callbacks
      Returns:
        true for a successful download, false otherwise. The return value is only relevant when `ignoreErrors` is true, as when false all failures raise BuildExceptions.
      Throws:
        `java.io.IOException` - for network trouble
        `BuildException` - for argument errors, or other trouble when ignoreErrors is false.
      Since:
        Ant 1.8.0

    - #### log

          public void log(java.lang.String msg,
                 int msgLevel)

      Description copied from class: `Task`
      Logs a message with the given priority. This delegates the actual logging to the project.
      Overrides:
        `log` in class `Task`
      Parameters:
        `msg` - The message to be logged. Should not be `null`.
        `msgLevel` - The message priority at which this message is to be logged.

    - #### setSrc

          public void setSrc(java.net.URL u)

      Set an URL to get.
      Parameters:
        `u` - URL for the file.

    - #### add

          public void add(ResourceCollection rc)

      Adds URLs to get.
      Since:
        Ant 1.8.0

    - #### setDest

          public void setDest(java.io.File dest)

      Where to copy the source file.
      Parameters:
        `dest` - Path to file.

    - #### setVerbose

          public void setVerbose(boolean v)

      If true, show verbose progress information.
      Parameters:
        `v` - if "true" then be verbose

    - #### setQuiet

          public void setQuiet(boolean v)

      If true, set default log level to Project.MSG_ERR.
      Parameters:
        `v` - if "true" then be quiet
      Since:
        Ant 1.9.4

    - #### setIgnoreErrors

          public void setIgnoreErrors(boolean v)

      If true, log errors but do not treat as fatal.
      Parameters:
        `v` - if "true" then don't report download errors up to ant

    - #### setUseTimestamp

          public void setUseTimestamp(boolean v)

      If true, conditionally download a file based on the timestamp of the local copy.

      In this situation, the if-modified-since header is set so that the file is only fetched if it is newer than the local file (or there is no local file) This flag is only valid on HTTP connections, it is ignored in other cases. When the flag is set, the local copy of the downloaded file will also have its timestamp set to the remote file time.

      Note that remote files of date 1/1/1970 (GMT) are treated as 'no timestamp', and web servers often serve files with a timestamp in the future by replacing their timestamp with that of the current time. Also, inter-computer clock differences can cause no end of grief.

      Parameters:
        `v` - "true" to enable file time fetching

    - #### setUsername

          public void setUsername(java.lang.String u)

      Username for basic auth.
      Parameters:
        `u` - username for authentication

    - #### setPassword

          public void setPassword(java.lang.String p)

      password for the basic authentication.
      Parameters:
        `p` - password for authentication

    - #### setMaxTime

          public void setMaxTime(long maxTime)

      The time in seconds the download is allowed to take before being terminated.
      Since:
        Ant 1.8.0

    - #### setRetries

          public void setRetries(int r)

      The number of retries to attempt upon error, defaults to 3.
      Parameters:
        `r` - retry count
      Since:
        Ant 1.8.0

    - #### setSkipExisting

          public void setSkipExisting(boolean s)

      Skip files that already exist locally.
      Parameters:
        `s` - "true" to skip existing destination files
      Since:
        Ant 1.8.0

    - #### setUserAgent

          public void setUserAgent(java.lang.String userAgent)

      HTTP connections only - set the user-agent to be used when communicating with remote server. if null, then the value is considered unset and the behaviour falls back to the default of the http API.
      Since:
        Ant 1.9.3

    - #### setHttpUseCaches

          public void setHttpUseCaches(boolean httpUseCache)

      HTTP connections only - control caching on the HttpUrlConnection: httpConnection.setUseCaches(); if false, do not allow caching on the HttpUrlConnection.

      Defaults to true (allow caching, which is also the HttpUrlConnection default value.

      Since:
        Ant 1.8.0

    - #### setTryGzipEncoding

          public void setTryGzipEncoding(boolean b)

      Whether to transparently try to reduce bandwidth by telling the server ant would support gzip encoding.

      Setting this to true also means Ant will uncompress `.tar.gz` and similar files automatically.

      Since:
        Ant 1.9.5

    - #### createMapper

          public Mapper createMapper()
                              throws BuildException

      Define the mapper to map source to destination files.
      Returns:
        a mapper to be configured.
      Throws:
        `BuildException` - if more than one mapper is defined.
      Since:
        Ant 1.8.0

    - #### add

          public void add(FileNameMapper fileNameMapper)

      Add a nested filenamemapper.
      Parameters:
        `fileNameMapper` - the mapper to add.
      Since:
        Ant 1.8.0